docs: refresh SDK guides and references - #113
Merged
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
TL;DRThe SDK documentation now describes current tracing, scoring, prompt, lifecycle, and data-read contracts through a task-based structure.
Change diagram
flowchart LR accTitle: Documentation structure before and after accDescr: The documentation changes from overlapping guides to a task hub with current workflows, references, and verification. subgraph Before["Before"] A["Overlapping guides"] --> B["Unclear verification path"] end subgraph After["After"] C["Task hub"] --> D["Workflow guide"] D --> E["API reference"] D --> F["SDK and CLI verification"] endWhyRecent SDK changes added v4 data reads, prompt variables, score delivery modes, and lifecycle controls. The earlier guides split these contracts across multiple pages. Some wording was informal or inconsistent.
This PR organizes the guides by task. It adds a data-access and verification guide. It also applies ASD-STE100 writing principles to the changed documentation.
The root README stays minimal. Detailed guidance remains in
docs/. The broad documentation diff requires reviewers to verify technical terms and cross-page consistency.ChecklistVerification
I validated the branch locally at commit
59eb267. The full RSpec suite passed 1,636 examples. Line coverage was 96.93%.RuboCop inspected 108 files and found no offenses. I checked local Markdown links and code fences. I also parsed 175 Ruby examples from the changed guides.
I queried observations, metrics, and scores through the SDK with the configured test project. I also queried observations and scores through
langfuse-cli@latest. Both CLI reads returned HTTP 200.I did not preview the rendered Mermaid diagram. GitHub must render the diagram after PR creation.
Note
Low Risk
Documentation-only changes with tiny comment/YARD updates in lib; no production code paths altered in the diff.
Overview
This PR is a documentation refresh that aligns the guides with current SDK behavior rather than introducing new runtime features in the diff.
Structure and tone:
docs/README.mdbecomes a task-oriented hub with a production checklist. Guides are rewritten in clearer, more formal language (ASD-STE100-style), with less informal wording and more consistent terminology across pages.New and expanded coverage: Adds
docs/DATA_ACCESS.mdfor choosing amonglist_observations,query_metrics, andlist_scores, cursor pagination, and end-to-end verification via the SDK and Langfuse CLI.CHANGELOG.mdanddocs/API_REFERENCE.mddocument v2/v3 read APIs,TextPromptClient#variables/ChatPromptClient#variables, synchronous vs asynchronous scoring (create_score!),tracing_enabled/LANGFUSE_TRACING_ENABLED, bounded score queues, v4 OTLP ingestion, fork/exit lifecycle, and related config env vars.Workflow updates: Getting Started, Tracing, Scoring, Configuration, and Rails now emphasize flush/readback verification, runtime mode tables (
tracing_enabledvsOTEL_SDK_DISABLED), automatic exit flush (and dropping redundantat_exitexamples), and explicit trace/job context passing. Architecture reflects bounded score batching, masking exporter, fork safety, and process lifecycle. Minor YARD/example tweaks inlib/langfuse.rb,config.rb, and prompt clients match the documented APIs.Risk: Reviewers should spot-check technical accuracy and cross-links across the large doc surface; behavior changes are mostly already in the SDK鈥攖he PR makes them discoverable.
Reviewed by Cursor Bugbot for commit 59eb267. Bugbot is set up for automated code reviews on this repo. Configure here.